---
{
	"title": "Favicon",
	"language": "en",
	"category": "Plugins",
	"categoryfile": "plugins",
	"description": "This plugin provides the ability to add and update a web page's favicon.",
	"altLangPrefix": "favicon",
	"dateModified": "2014-08-04"
}
---
<span class="wb-prettify all-pre hide"></span>

<section>
	<h2>Purpose</h2>
	<p>This plugin provides the ability to add and update a web page's favicon.</p>
</section>

<section>
	<h2>Use when</h2>
	<ul>
		<li>Adding a mobile favicon to a web page.</li>
		<li>Dynamically updating the favicon of a web page.</li>
	</ul>
</section>

<section>
	<h2>Working example</h2>
	<p><a href="../../../demos/favicon/favicon-en.html">English example</a></p>
	<p><a href="../../../demos/favicon/favicon-fr.html">French example</a></p>
</section>

<section>
	<h2>How to implement</h2>

	<section>
		<h3>Add a mobile favicon:</h3>
		<ol>
			<li>Add a favicon to the web page using a link element:
				<pre><code>&lt;link href="favicon.ico" rel="icon" type="image/x-icon"&gt;</code></pre>
			</li>
			<li>Optionally specify the mobile favicon's filename, path, rel attribute and sizes attribute:
				<pre><code>&lt;link href="favicon.ico" rel="icon" type="image/x-icon"
	data-filename="my-mobile-favicon.ico"
	data-path="/path/to/favicon/"
	data-rel="apple-touch-icon-precomposed"
	data-sizes="57x57"&gt;</code></pre>
			</li>
		</ol>
	</section>

	<section>
		<h3>Update an existing favicon's href attribute:</h3>
		<ol>
			<li>Using JavaScript, get a reference to the favicon's link element:
				<pre><code>var $favicon = $( "link[rel='icon']" );</code></pre>
			</li>
			<li>Trigger the <code>icon.wb-favicon</code> event on the favicon element:
				<pre><code>$favicon.trigger( "icon.wb-favicon" );</code></pre>
				<strong>Note:</strong> the update of the favicon's href attribute will be based on its data-path and data-filename attributes.
			</li>
		</ol>
	</section>
</section>

<section>
	<h2>Configuration options</h2>
	<p>All configuration options of the plugin are controlled with data attributes:</p>

	<table class="table">
		<thead>
			<tr>
				<th>Option</th>
				<th>Description</th>
				<th>How to configure</th>
				<th>Values</th>
			</tr>
		</thead>
		<tbody>
			<tr>
				<td><code>data-filename</code></td>
				<td>Filename of the mobile favicon. It is appended to the favicon's path (specified by data-path).</td>
				<td>Set to the filename of the mobile favicon.</td>
				<td>
					<dl>
						<dt>None (default):</dt>
						<dd>If not specified, defaults to "favicon-mobile.png"</dd>
						<dt>String (favicon filename):</dt>
						<dd>Custom mobile favicon filename.</dd>
					</dl>
				</td>
			</tr>
			<tr>
				<td><code>data-path</code></td>
				<td>Full path to the mobile favicon.</td>
				<td>Set to the full path of the mobile favicon.</td>
				<td>
					<dl>
						<dt>None (default):</dt>
						<dd>If not specified, defaults to the same path as the <code>&lt;link&gt;</code> icon</dd>
						<dt>String (favicon path):</dt>
						<dd>Custom mobile favicon path.</dd>
					</dl>
				</td>
			</tr>
			<tr>
				<td><code>data-rel</code></td>
				<td>Favicon rel attribute.</td>
				<td>Set to the desired rel attribute value of the favicon.</td>
				<td>
					<dl>
						<dt>None (default):</dt>
						<dd>If not specified, defaults to "apple-touch-icon"</dd>
						<dt>String (favicon rel attribute):</dt>
						<dd>Custom mobile favicon <a href="https://en.wikipedia.org/wiki/Favicon#How_to_use">rel attribute</a>.</dd>
					</dl>
				</td>
			</tr>
			<tr>
				<td><code>data-sizes</code></td>
				<td>Favicon sizes attribute.</td>
				<td>Set to the desired sizes attribute value of the favicon.</td>
				<td>
					<dl>
						<dt>None (default):</dt>
						<dd>If not specified, defaults to "57x57 72x72 114x114 144x144 150x150"</dd>
						<dt>String (favicon sizes attribute):</dt>
						<dd>Custom mobile favicon sizes attribute.</dd>
					</dl>
				</td>
			</tr>
		</tbody>
	</table>
</section>

<section>
	<h2>Events</h2>
	<p>Document the public events that can be used by implementers or developers.</p>
	<table class="table">
		<thead>
			<tr>
				<th>Event</th>
				<th>Trigger</th>
				<th>What it does</th>
			</tr>
		</thead>
		<tbody>
			<tr>
				<td><code>wb-init.wb-favicon</code></td>
				<td>Triggered manually (e.g., <code>$( "link[rel='icon']" ).trigger( "wb-init.wb-favicon" );</code>).</td>
				<td>Initializes the plugin and creates a mobile favicon if it doesn't already exist. <strong>Note:</strong> the favicon plugin will be initialized automatically unless the link element is added after the page has already loaded.</td>
			</tr>
			<tr>
				<td><code>wb-ready.wb-favicon</code> (v4.0.5+)</td>
				<td>Triggered automatically after the Favicon plugin initializes.</td>
				<td>Used to identify when the Favicon plugin has initialized
					<pre><code>$( document ).on( "wb-ready.wb-favicon", "link[rel='icon']", function( event ) {
});</code></pre>
					<pre><code>$( "link[rel='icon']" ).on( "wb-ready.wb-favicon", function( event ) {
});</code></pre>
				</td>
			</tr>
			<tr>
				<td><code>wb-updated.wb-favicon</code> (v4.0.5+)</td>
				<td>Triggered automatically after the favicon update has completed.</td>
				<td>Used to identify when the plugin has finished updating the favicon and to pass along what type of favicon was updated (<code>mobile</code>, <code>icon</code>).
					<pre><code>$( document ).on( "wb-updated.wb-favicon", "link[rel='icon']", function( event ) {
});</code></pre>
					<pre><code>$( "link[rel='icon']" ).on( "wb-updated.wb-favicon", function( event ) {
});</code></pre>
				</td>
			</tr>
			<tr>
				<td><code>mobile.wb-favicon</code></td>
				<td>Triggered manually and during plugin initialization (e.g., <code>$( "link[rel='icon']" ).trigger( "mobile.wb-favicon" );</code>).</td>
				<td>Adds or updates the mobile favicon on the web page. This will only update a mobile favicon that was added by the plugin.</td>
			</tr>
			<tr>
				<td><code>icon.wb-favicon</code></td>
				<td>Triggered manually (e.g., <code>$( "link[rel='icon']" ).trigger( "icon.wb-favicon" );</code>).</td>
				<td>Updates the favicon's <code>href</code> attribute based on its <code>data-filename</code> and <code>data-path</code> attributes.</td>
			</tr>
			<tr>
				<td><code>wb-ready.wb</code> (v4.0.5+)</td>
				<td>Triggered automatically when WET has finished loading and executing.</td>
				<td>Used to identify when all WET plugins and polyfills have finished loading and executing.
					<pre><code>$( document ).on( "wb-ready.wb", function( event ) {
});</code></pre>
				</td>
			</tr>
		</tbody>
	</table>
</section>

<section>
	<h2>Source code</h2>
	<p><a href="https://github.com/wet-boew/wet-boew/tree/master/src/plugins/favicon">Favicon source code on GitHub</a></p>
</section>
